Deprecate standalone package: Pipecat Flows is now part of Pipecat - #290

Companion to pipecat-ai/pipecat#4882, which folds Pipecat Flows into core pipecat-ai under the pipecat.flows namespace.

This PR turns pipecat-ai-flows into its final, frozen snapshot before the repo is archived:

• Deprecation warning — importing pipecat_flows now emits a DeprecationWarning pointing at pipecat.flows. The code is otherwise unchanged and still works.
• Dependency pin — pipecat-ai>=1.4.0,<1.5.0, the last Pipecat line without built-in Flows. This package stays the Flows provider for that era and deliberately cannot coexist with a pipecat-ai that already bundles pipecat.flows — so upgrading Pipecat past 1.4.x forces dropping this package and importing pipecat.flows. That's the migration pressure, done cleanly, and it resolves/tests against current Pipecat today.
• README — replaced with a short redirect: before/after import, where things moved, and a pointer to the archived changelog. The standalone release history stays in CHANGELOG.md.

Why a clean break, not a pipecat_flows → pipecat.flows shim

An alternative was to make this package a thin re-export shim — pipecat_flows simply does from pipecat.flows import * and forwards to the in-core framework, so existing from pipecat_flows import ... code keeps working transparently. We deliberately didn't, for a few reasons:

• A shim can't be "frozen." By construction it forwards to whatever pipecat.flows is installed, so it would keep delivering new Flows behavior indefinitely — the opposite of a final, frozen release. Stopping that would mean pinning pipecat-ai to an exact version, which is brittle.
• A shim would require the thing it supersedes. Forwarding to pipecat.flows means depending on pipecat-ai>=1.5.0 — i.e. installing the standalone package and the built-in one side by side, exactly the redundant dual-install we're steering people away from.
• The frozen snapshot is mutually exclusive with built-in Flows. Pinning <1.5.0 (the pre-Flows line) means this package and a pipecat.flows-bearing Pipecat can't be installed together, so upgrading Pipecat forces a clean migration to pipecat.flows rather than letting pipecat_flows imports live on forever with no nudge.
• It avoids an open-ended compatibility commitment. A perpetual forwarding layer is something core Pipecat would implicitly have to keep working across future versions; a frozen final release tied to the 1.4.x era has a clear, bounded end.

For the one case a shim wouldn't have helped with anyway — an older pipecat-ai-flows (which allowed pipecat-ai<2) installed next to a Pipecat that already has Flows — core Pipecat now logs an error on import pipecat.flows telling the user to uninstall the standalone package (see pipecat#4882).

Sequencing

Not blocked on the 1.5.0 release (it pins to 1.4.x, which exists today), but the migration target it points users at — pipecat.flows — only exists once pipecat#4882 lands and pipecat-ai 1.5.0 ships. So:

• Release this as the final pipecat-ai-flows around/after 1.5.0 is out, so from pipecat.flows import ... actually works for anyone following the warning.
• After the final release, archive this repository.
• If pipecat.flows first ships in a version other than 1.5.0, set the cap to < <that version> (the first Pipecat with built-in Flows) and update the README's "as of pipecat-ai 1.5.0" reference to match.

🤖 Generated with Claude Code